🎟️ TeamDynamix MCP Server (unofficial)

A TypeScript Model Context Protocol (MCP) server that exposes TeamDynamix ITSM capabilities as agent-callable tools. Designed for AI agents and MCP clients that need structured, safety-gated access to TeamDynamix operations.

Features

• 11 domain gateway tools that route validated actions across discovery, tickets, relationships, KB, assets, CMDB, people, services, projects, time, and reference data
• Safe by default: write tools disabled until explicitly opted in; destructive operations require confirm: true
• Two auth modes: standard (username/password) and admin (BEID/WebServicesKey)
• Rate-limit aware: auto-retry with backoff on 429 responses
• Zod-validated inputs: schema enforcement before any API call
• Agent skill and prompt included: ready-to-use skill definition for GitHub Copilot and compatible agents

Minimum required environment variables

TEAMDYNAMIX_BASE_URL=https://your-tenant.teamdynamix.com/TDWebApi
TEAMDYNAMIX_AUTH_MODE=standard          # or: admin
TEAMDYNAMIX_USERNAME=you@example.com    # standard mode
TEAMDYNAMIX_PASSWORD=your-password      # standard mode

For admin mode, use TEAMDYNAMIX_BEID and TEAMDYNAMIX_WEB_SERVICES_KEY instead.

MCP client configuration

Security notice: Values shown above are placeholders. Never commit real credentials to source control. Inject secrets at runtime via a .env file (excluded by .gitignore), CI/CD secrets, or a secret manager.

VS Code (.vscode/mcp.json)

{
  "servers": {
    "teamdynamix": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@selfagency/teamdynamix-mcp"],
      "env": {
        "TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
        "TEAMDYNAMIX_AUTH_MODE": "standard",
        "TEAMDYNAMIX_USERNAME": "you@example.com",
        "TEAMDYNAMIX_PASSWORD": "your-password"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "teamdynamix": {
      "command": "npx",
      "args": ["-y", "@selfagency/teamdynamix-mcp"],
      "env": {
        "TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
        "TEAMDYNAMIX_AUTH_MODE": "standard",
        "TEAMDYNAMIX_USERNAME": "you@example.com",
        "TEAMDYNAMIX_PASSWORD": "your-password"
      }
    }
  }
}

Production (built bundle)

pnpm build   # outputs to dist/

{
  "command": "npx",
  "args": ["-y", "@selfagency/teamdynamix-mcp"]
}

Verify connectivity

After connecting your MCP client, call teamdynamix_discovery with:

• action: "server_status"
• payload: {}
• response_format: "json"

A successful response shows status.configured: true.

Domain gateway tools

Each gateway tool accepts:

• action: domain-specific operation name
• payload: object for that action’s parameters
• response_format: "markdown" or "json"

† Requires confirm: true in addition to write tools being enabled.

All write/mutating actions require TEAMDYNAMIX_ENABLE_WRITE_TOOLS=true.

Safety defaults

Destructive unlink operations additionally require confirm: true in the tool call regardless of write flag state.

Agent skill

This repository ships a GitHub Copilot-compatible skill definition:

• Skill: skills/teamdynamix/SKILL.md — ID-first workflow patterns, safety branching rules, runbooks, gotchas, and tool catalog
• Agent prompt: prompts/teamdynamix-agent.prompt.md — system prompt for agent mode with TeamDynamix context

Install the skill via your Copilot skill configuration (see skills/teamdynamix/SKILL.md for full details).

Documentation

License

MIT © The Self Agency LLC